package net.sourceforge.jsocks;

/**
 * The Authentication interface provides for performing method specific
 * authentication for SOCKS5 connections.
 */
public interface Authentication {
    /**
     * This method is called when SOCKS5 server have selected a particular
     * authentication method, for whch an implementaion have been registered.
     *
     * <p>
     * This method should return an array {inputstream,outputstream
     * [,UDPEncapsulation]}. The reason for that is that SOCKS5 protocol allows
     * to have method specific encapsulation of data on the socket for purposes
     * of integrity or security. And this encapsulation should be performed by
     * those streams returned from the method. It is also possible to
     * encapsulate datagrams. If authentication method supports such
     * encapsulation an instance of the UDPEncapsulation interface should be
     * returned as third element of the array, otherwise either null should be
     * returned as third element, or array should contain only 2 elements.
     *
     * @param methodId    Authentication method selected by the server.
     * @param proxySocket Socket used to conect to the proxy.
     * @return Two or three element array containing Input/Output streams which
     * should be used on this connection. Third argument is optional and
     * should contain an instance of UDPEncapsulation. It should be
     * provided if the authentication method used requires any
     * encapsulation to be done on the datagrams.
     */
    Object[] doSocksAuthentication(int methodId, java.net.Socket proxySocket)
            throws java.io.IOException;
}
